Creating a GitHub pages site with MkDocs

In Module 5, you learned how to set up and serve a basic webpage on GitHub's gh-pages. GitHub allows you to host a website on a personal URL with the syntax https://myname.github.io. Many developers will use a static site generator to create a simple website run on gh-pages. Some popular static site generators are Jekyll, Hugo, and MkDocs. In fact, this website is built with MkDocs.

Static site generators are command line tools that use templates to build and create websites. Users define basic information in a yaml or toml filetype, write in markdown, and use a simple command to build it into a functioning static site. Due to the popularity of static site generators, most contain simple methods to link it to gh-pages.

In this exercise, we will use MkDocs in the DH Box to build a site that updates to GitHub and pushes changes to a https://myname.github.io URL. We will use DH Box to download MkDocs and build the site. Although your changes will be saved in a GitHub repository, when your DH Box account expires, you will have to clone the website again and redownload everything. Therefore, if you want to use your MkDocs site past the purposes of this course, you may want to follow these steps on your desktop. These steps will be similar to using Mac's terminal, but may be different on a Windows machine.

Preparing MkDocs in DH Box

Navigate to the DH Box command line.
Type $ sudo pip install mkdocs into the command line.
Type $ mkdocs --version to ensure MkDocs was installed properly.
Type $ mkdocs new my-site or whatever you want your site to be called. Mine is called static-site.
Typically, you could now view your site in your browser by typing $ mkdocs serve. This would not work within DH Box, though, since DH Box runs as a virtual environment within your browser. It would work from your desktop terminal.
Type $ ls to view the files MkDocs created. You will define your site within the mkdocs.yml file.
Type $ nano mkdocs.yml to open the config file.
Change the site_name to your site's name.
Paste the following underneath site_name:
```
pages:
    - Home: index.md
theme: readthedocs
```
This sets up our Home and About pages and adds the theme called Read the Docs.
Hit ctrl-x, Y, enter to save and exit nano.

Creating a git repository

Navigate to GitHub and create a new repository with the same name as your MkDocs folder. For example, my MkDocs folder is called static-site. Therefore, I call my GitHub repository static-site.
Navigate back to the command line.
Type $ git init to initialize the MkDocs folder as a git repository.
Type $ git add . to add the files and folders.
Type $ git commit -m "First commit" to commit your changes.
Type $ git remote add origin https://github.com/<yourusername>/<yourrepository>.git, making sure to add your URL to the GitHub repository.
Type $ git push -u origin master to push your changes.
Type $ mkdocs gh-deploy to push your folder to a gh-pages site.

MkDocs will show a message which says the following:
```
INFO    -  Your documentation should shortly be available at: https://myname.github.io/my-site/`.
```
The above means it pushed your changes to a project folder called my-site and not the main https://myname.github.io/.
Navigate to your URL https://myname.github.io/my-site/. You should now see a webpage that looks a lot like this workbook.

Adding content to your site

Let's say we now want to add an About page and a Blog page to our site. We need to define and create these files.

Navigate to the command line.
Type $ ls to view your MkDocs files and folders. You will notice now a site folder has been generated. This is simply the site folder created by MkDocs which is served on your github.io site.
Type $ nano mkdocs.yml to open the config file.

Add an about page and a posts page. Your file should contain the following:

site_name: Static Site Example
pages:
    - Home: index.md
    - About: about.md
    - Blog: blog.md
theme: readthedocs

Hit ctrl-x, Y, enter to save and exit nano.
Type $ cd docs to enter the docs folder.
Type $ touch about.md to create the About file and touch blog.md to create the Blog file.
Type $ ls to make sure the files were created.
Type $ cd .. to go back to the main MkDocs folder.
Type $ git add . to add the files.
Type $ git commit -m "Added about and blog files" to commit your changes.
Type $ git push -u origin master to push your changes.

This ensures all your changes are pushed to your GitHub repository.
Type $ mkdocs gh-deploy to push your folder to a gh-pages site.
Reload your gh-pages site https://myname.github.io/.

It may take some time for your changes to update to your gh-pages site.
Back in your docs folder, you can use nano to edit any of the markdown files. If you add any files, make sure to declare them in mkdocs.yml.

Customizing your theme

MkDocs also allows you to customize your theme. We don't want to directly edit the theme files, so we will create a new one.

Navigate to the command line.
In your main MkDocs folder, type $ nano mkdocs.yml to open your configuration file.
Add the following text below the other configuration details:
```
extra_css:
  - 'css/extra.css'
```
This declaration tells the site to first look for styles in a folder called css in a file called extra.css before going to the default theme.
Hit ctrl-x, Y, enter to save and exit nano.
Type $ cd docs to navigate to the docs folder.
Type $ mkdir css to create a folder called css.
Type $ cd css to enter the css folder.
Type $ nano extra.css to create an enter a css file called extra.

Let's change the font of our site to Open Sans.

Add the following to your css file:

h1, h2, h3, h4, h5, h6, legend {
    font-family: 'Open Sans', sans-serif;
}

Hit ctrl-x, Y, enter to save and exit nano.
Type $ cd .. twice to go back up to your main MkDocs folder.
Use git to add your files, commit, push, and then use mkdocs to deploy to gh-pages to view your changes.

You can now use you knowledge to customize your theme. Remember to use your browser inspector tool to check which rules you want to change.